<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.5">
<meta name="author" content="2019-08-08 13:15:33 CEST">
<title>N4JS Design Specification</title>
<link rel="stylesheet" href="styles/spec.min.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css">
<!-- ************* docinfo ******************************************************************* -->


<!-- ************* Favicon ************-->
<link rel="icon" href="images/favicon.ico" />

<!-- ************* Back-to-top JQuery ************* -->
<script src="https://code.jquery.com/jquery-1.12.4.js"></script>
<script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script>


<link href="styles/prism.min.css" rel="stylesheet" />
<script type="text/javascript" async
  src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-MML-AM_CHTML">
</script>

<!-- ************* Styles ************* -->
<link rel="stylesheet" type="text/css" href="styles/n4jsspec-adoc.css">


<!-- ****************** NavBar ****************** -->
<div id="menubar">
	<div class="banner">
        <a href="https://www.eclipse.org/n4js/#"><img id="logo" src="images/n4js-logo.png" alt="Eclipse N4JS"></a>
    </div>
<ul>
  <li><a href="index.html">Index</a></li>
</ul>
</div>
<!-- ************* docinfo ******************************************************************* -->
<style>
      .admonitionblock td.icon .icon-todo:before{content:"\f249";color:#f4ee42}
    </style>
</head>
<body class="book toc2 toc-left">
<div id="header">
<h1>N4JS Design Specification</h1>
<div class="details">
<span id="author" class="author">2019-08-08 13:15:33 CEST</span><br>
<span id="revnumber">version 0.9</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="introduction.html#_introduction">1. Introduction</a>
<ul class="sectlevel2">
<li><a href="introduction.html#notation">1.1. Notation</a></li>
<li><a href="introduction.html#sec:IDE_Overview">1.2. IDE Components</a>
<ul class="sectlevel3">
<li><a href="introduction.html#sec:Naming_Conventions">1.2.1. Naming Conventions</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="eclipse_setup.html#_eclipse-setup">2. Eclipse Setup</a>
<ul class="sectlevel2">
<li><a href="eclipse_setup.html#_system-requirements">2.1. System Requirements</a></li>
<li><a href="eclipse_setup.html#_contribute">2.2. Contribute</a>
<ul class="sectlevel3">
<li><a href="eclipse_setup.html#_eclipse-installer">2.2.1. Eclipse Installer</a>
<ul class="sectlevel4">
<li><a href="eclipse_setup.html#_changing-the-setup-script">2.2.1.1. Changing the Setup Script</a></li>
</ul>
</li>
<li><a href="eclipse_setup.html#_manual-ide-configuration">2.2.2. Manual IDE Configuration</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="release_engineering.html#_release-engineering">3. Release Engineering</a>
<ul class="sectlevel2">
<li><a href="release_engineering.html#_nightly-build-on-eclipse-infrastructure">3.1. Nightly build on Eclipse infrastructure</a></li>
<li><a href="release_engineering.html#_build-the-n4js-ide-from-command-line">3.2. Build the N4JS IDE from command line</a>
<ul class="sectlevel3">
<li><a href="release_engineering.html#_publish-maven-tooling-code-org-eclipse-n4js-releng-util-code">3.2.1. Publish maven-tooling <code>org.eclipse.n4js.releng.util</code></a></li>
<li><a href="release_engineering.html#sec:test-verdaccio">3.2.2. Test Verdaccio containing n4js-libs</a></li>
<li><a href="release_engineering.html#_generation-of-eclipse-help-for-spec-and-design-document">3.2.3. Generation of Eclipse help for spec and design document</a></li>
</ul>
</li>
<li><a href="release_engineering.html#_updating-frameworks-and-dependencies">3.3. Updating frameworks and dependencies</a>
<ul class="sectlevel3">
<li><a href="release_engineering.html#_update-of-eclipse-emf-xtext-etc">3.3.1. Update of Eclipse, EMF, Xtext, etc.</a></li>
<li><a href="release_engineering.html#_update-of-the-embedded-jre">3.3.2. Update of the embedded JRE</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tips_and_tricks.html#_tips-and-tricks">4. Tips and Tricks</a>
<ul class="sectlevel2">
<li><a href="tips_and_tricks.html#_naming">4.1. Naming</a></li>
<li><a href="tips_and_tricks.html#_logging">4.2. Logging</a></li>
<li><a href="tips_and_tricks.html#_cancellation-handling">4.3. Cancellation Handling</a></li>
<li><a href="tips_and_tricks.html#_caching">4.4. Caching</a></li>
<li><a href="tips_and_tricks.html#_dependency-injection">4.5. Dependency Injection</a></li>
<li><a href="tips_and_tricks.html#_miscellaneous">4.6. Miscellaneous</a></li>
</ul>
</li>
<li><a href="parser.html#_parser">5. Parser</a>
<ul class="sectlevel2">
<li><a href="parser.html#sec:Parser_Overview">5.1. Overview</a></li>
<li><a href="parser.html#sec:N4JS_Parser">5.2. N4JS Parser</a></li>
<li><a href="parser.html#sec:Parser_Generation_Post_Processing">5.3. Parser Generation Post-Processing</a>
<ul class="sectlevel3">
<li><a href="parser.html#sec:Automatic_Semicolon_Insertion">5.3.1. Automatic Semicolon Insertion</a>
<ul class="sectlevel4">
<li><a href="parser.html#sec:Injected_code_in_the_Antlr_grammar_file">5.3.1.1. Injected code in the Antlr grammar file</a></li>
<li><a href="parser.html#sec:Customized_error_recovery">5.3.1.2. Customized error recovery</a></li>
</ul>
</li>
<li><a href="parser.html#sec:_No_line_terminator_allowed_here__handling">5.3.2. Async and <code>No line terminator allowed here</code> Handling</a></li>
<li><a href="parser.html#sec:Regular_Expression">5.3.3. Regular Expression</a></li>
<li><a href="parser.html#sec:Unicode">5.3.4. Unicode</a></li>
<li><a href="parser.html#sec:Literals">5.3.5. Literals</a></li>
</ul>
</li>
<li><a href="parser.html#sec:Modifiers">5.4. Modifiers</a></li>
<li><a href="parser.html#sec:Conflict_Resolutions">5.5. Conflict Resolutions</a>
<ul class="sectlevel3">
<li><a href="parser.html#sec:Reserved_Keywords_vs__Identifier_Names">5.5.1. Reserved Keywords vs. Identifier Names</a></li>
<li><a href="parser.html#sec:Operators_and_Generics">5.5.2. Operators and Generics</a></li>
</ul>
</li>
<li><a href="parser.html#sec:Content_Assist_Parser">5.6. Content-Assist Parser</a></li>
</ul>
</li>
<li><a href="#_type-system">6. Type System</a>
<ul class="sectlevel2">
<li><a href="#sec:Type_Model_and_Grammar">6.1. Type Model and Grammar</a>
<ul class="sectlevel3">
<li><a href="#sec:Type_Model_Overview">6.1.1. Type Model Overview</a></li>
<li><a href="#sec:Built_in_Types">6.1.2. Built-in and Primitive Types</a></li>
<li><a href="#sec:Type_Model_DSL">6.1.3. Type Model DSL</a></li>
</ul>
</li>
<li><a href="#sec:Type_System_Implementation">6.2. Type System Implementation</a></li>
<li><a href="#sec:Type_Inference_combined_with_AST_Traversal">6.3. Type Inference of AST</a>
<ul class="sectlevel3">
<li><a href="#sec:Type_Inference_combined_with_AST_Traversal__Background">6.3.1. Background</a></li>
<li><a href="#sec:Triggering_Type_Inference_of_AST">6.3.2. Triggering</a></li>
<li><a href="#sec:Traversal_Order_During_Type_Inference_of_AST">6.3.3. Traversal Order</a></li>
<li><a href="#sec:Cross_References_During_Type_Inference_of_AST">6.3.4. Cross-References</a></li>
<li><a href="#sec:Function_Accessor_Bodies_During_Type_Inference_of_AST">6.3.5. Function/Accessor Bodies</a></li>
<li><a href="#sec:Poly_Expressions_During_Type_Inference_of_AST">6.3.6. Poly Expressions</a></li>
<li><a href="#sec:Constraint_Solver_used_During_Type_Inference_of_AST">6.3.7. Constraint Solver</a></li>
<li><a href="#sec:Type_Guards_During_Type_Inference_of_AST">6.3.8. Type Guards</a></li>
</ul>
</li>
<li><a href="#sec:Structural_Typing">6.4. Structural Typing</a></li>
</ul>
</li>
<li><a href="type_index.html#_type-index">7. Type Index</a>
<ul class="sectlevel2">
<li><a href="type_index.html#sec:Type_Index_Design_Rationale">7.1. Design Rationale</a>
<ul class="sectlevel3">
<li><a href="type_index.html#sec:Getting_the_Xtext_Index_Content_IResourceDescriptions">7.1.1. Getting the Xtext Index (<code>IResourceDescriptions</code>) Content</a></li>
</ul>
</li>
<li><a href="type_index.html#sec:Design_Overview">7.2. Design Overview</a></li>
<li><a href="type_index.html#sec:N4JS_Resource_Load_States">7.3. N4JS Resource Load States</a></li>
<li><a href="type_index.html#sec:Type_Builder">7.4. Types Builder</a>
<ul class="sectlevel3">
<li><a href="type_index.html#sec:Type_Inference_not_allowed_in_Type_Builder">7.4.1. Type Inference not allowed in Types Builder</a></li>
<li><a href="type_index.html#sec:ComputedTypeReferences">7.4.2. Deferred Type References</a></li>
<li><a href="type_index.html#sec:Use_cases_of_ComputedTypeRef">7.4.3. Use cases of DeferredTypeRef</a></li>
</ul>
</li>
<li><a href="type_index.html#sec:Incremental_Builder_Overview">7.5. Incremental Builder (Overview)</a>
<ul class="sectlevel3">
<li><a href="type_index.html#sec:Incremental_Builder_Overview__XtextBuilder">7.5.1. XtextBuilder</a></li>
<li><a href="type_index.html#sec:Incremental_Builder_Overview__IBuilderState">7.5.2. IBuilderState</a>
<ul class="sectlevel4">
<li><a href="type_index.html#copy-and-update-xtext-index">7.5.2.1. Copy and Update Xtext Index</a></li>
<li><a href="type_index.html#build-state-setup-phase">7.5.2.2. Build State Setup Phase</a></li>
<li><a href="type_index.html#process-queued-uris">7.5.2.3. Process Queued URIs</a></li>
<li><a href="type_index.html#queueing-affected-resources">7.5.2.4. Queueing Affected Resources</a></li>
</ul>
</li>
<li><a href="type_index.html#sec:Incremental_Builder_Overview__Example">7.5.3. Example</a></li>
</ul>
</li>
<li><a href="type_index.html#dirty-state-handling">7.6. Dirty state handling</a>
<ul class="sectlevel3">
<li><a href="type_index.html#use-case-restoring-types-from-user-data">7.6.1. Use case: Restoring types from user data</a></li>
<li><a href="type_index.html#use-case-updating-the-xtext-index">7.6.2. Use case: Updating the Xtext index</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="project_model.html#_project-model">8. Project Model</a>
<ul class="sectlevel2">
<li><a href="project_model.html#sec:Package_json">8.1. Package.json File</a></li>
<li><a href="project_model.html#_accessing-project-information">8.2. Accessing Project Information</a>
<ul class="sectlevel3">
<li><a href="project_model.html#sec:IN4JSCore">8.2.1. IN4JSCore</a></li>
<li><a href="project_model.html#sec:N4JSModel">8.2.2. N4JSModel</a></li>
<li><a href="project_model.html#sec:N4JSWorkspace">8.2.3. N4JSWorkspace</a></li>
<li><a href="project_model.html#sec:N4JSProject">8.2.4. N4JSProject</a></li>
<li><a href="project_model.html#sec:SourceContainer">8.2.5. SourceContainer</a></li>
<li><a href="project_model.html#sec:N4JSProjectsStateHelper">8.2.6. N4JSProjectsStateHelper</a></li>
</ul>
</li>
<li><a href="project_model.html#sec:Caching">8.3. Caching</a>
<ul class="sectlevel3">
<li><a href="project_model.html#_caching-of-externallibraryworkspace">8.3.1. Caching of ExternalLibraryWorkspace</a></li>
<li><a href="project_model.html#_caching-of-n4jsprojectsstatehelper">8.3.2. Caching of N4JSProjectsStateHelper</a></li>
</ul>
</li>
<li><a href="project_model.html#sec:WildcardPathFilter">8.4. WildcardPathFilter</a></li>
<li><a href="project_model.html#sec:ProjectUtils">8.5. ProjectUtils</a></li>
</ul>
</li>
<li><a href="binding.html#_binding">9. Binding</a>
<ul class="sectlevel2">
<li><a href="binding.html#sec:Binding_Design_Rationale">9.1. Design Rationale</a></li>
<li><a href="binding.html#sec:Binding_to_Members">9.2. Binding to Members</a></li>
<li><a href="binding.html#sec:Binding_Getter_Setter">9.3. Getter / Setter Binding</a></li>
<li><a href="binding.html#chap:Statics">9.4. Static Member Binding</a></li>
<li><a href="binding.html#sec:Binding_Enumeration">9.5. Enumeration Literals Binding</a></li>
<li><a href="binding.html#sec:Accessibility_of_types_and_members">9.6. Accessibility of types and members</a></li>
<li><a href="binding.html#sec:Member_Scope_Example">9.7. Member Scope Example</a></li>
<li><a href="binding.html#sec:Scoping_for_Members_of_Composed_Type_Explained">9.8. Scoping for Members of Composed Type (Union/Intersection) Example</a></li>
<li><a href="binding.html#sec:Binding_of_Structurally_References_Types">9.9. Structurally References Types</a></li>
<li><a href="binding.html#sec:Building">9.10. Building</a>
<ul class="sectlevel3">
<li><a href="binding.html#sec:Build_Phases">9.10.1. Build Phases</a></li>
<li><a href="binding.html#sec:Build_Scenarios">9.10.2. Build Scenarios</a></li>
<li><a href="binding.html#sec:Lazy_linking_problem">9.10.3. Lazy linking problem</a></li>
</ul>
</li>
<li><a href="binding.html#sec:Proxies_and_Proxy_Resolution">9.11. Proxies and Proxy Resolution (Overview)</a>
<ul class="sectlevel3">
<li><a href="binding.html#xtexts-lazy-linking-proxies">9.11.1. Xtext’s Lazy Linking Proxies</a></li>
<li><a href="binding.html#standard-emf-proxies">9.11.2. Standard EMF Proxies</a></li>
<li><a href="binding.html#_how-is-proxy-resolution-triggered">9.11.3. How is Proxy Resolution Triggered?</a></li>
<li><a href="binding.html#_when-is-proxy-resolution-allowed">9.11.4. When is Proxy Resolution Allowed?</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="validation.html#_validation">10. Validation</a>
<ul class="sectlevel2">
<li><a href="validation.html#sec:validation_overview">10.1. Validation overview</a></li>
<li><a href="validation.html#sec:validation_control_flow">10.2. Validation control flow</a></li>
<li><a href="validation.html#sec:validation_issue_ids">10.3. Issue IDs and Messages</a></li>
<li><a href="validation.html#sec:validation_usage_patterns">10.4. Usage Pattern</a></li>
<li><a href="validation.html#sec:validation_links">10.5. Links</a></li>
</ul>
</li>
<li><a href="references.html#_references">11. References</a>
<ul class="sectlevel2">
<li><a href="references.html#sec:usecases">11.1. Use cases</a></li>
<li><a href="references.html#sec:calculation_algorithm">11.2. Calculation algorithm</a>
<ul class="sectlevel3">
<li><a href="references.html#sec:Xtext_default_implementation">11.2.1. Xtext default implementation</a></li>
<li><a href="references.html#sec:N4_implementation">11.2.2. N4JS implementation</a></li>
</ul>
</li>
<li><a href="references.html#sec:PerformanceOfDependencyCalculation">11.3. Performance Of Dependency Calculation</a></li>
<li><a href="references.html#sec:kinds_of_references">11.4. Kinds of references</a>
<ul class="sectlevel3">
<li><a href="references.html#sec:Cross_References_to_be_ignored">11.4.1. Cross References to be ignored</a></li>
<li><a href="references.html#sec:Cross_References_to_be_handled">11.4.2. Cross References to be handled</a></li>
</ul>
</li>
<li><a href="references.html#sec:transitive_dependencies">11.5. Transitive dependencies</a></li>
<li><a href="references.html#sec:find-references">11.6. Find references</a>
<ul class="sectlevel3">
<li><a href="references.html#_background">11.6.1. Background</a></li>
<li><a href="references.html#_how-find-references-work">11.6.2. How Find References Work</a>
<ul class="sectlevel4">
<li><a href="references.html#_step-1-convert-cursor-position-to-declared-element">11.6.2.1. Step 1: Convert Cursor Position to Declared Element</a></li>
<li><a href="references.html#_step-2-convert-declared-element-to-target-uris">11.6.2.2. Step 2: Convert Declared Element to Target URIs</a></li>
<li><a href="references.html#_step-3-filter-potential-resources">11.6.2.3. Step 3: Filter Potential Resources</a></li>
<li><a href="references.html#_step-4-search-references-in-resource">11.6.2.4. Step 4: Search References in Resource</a></li>
<li><a href="references.html#_limitations-and-possible-enhancements">11.6.2.5. Limitations and Possible Enhancements</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="compilation.html#_compilation">12. Compilation</a>
<ul class="sectlevel2">
<li><a href="compilation.html#chap:compilation">12.1. Introduction</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:general_design_rationals">12.1.1. General design rationals</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:logging_and_error_reporting">12.1.1.1. Logging and error reporting</a></li>
<li><a href="compilation.html#sec:progress_monitor">12.1.1.2. Progress monitor</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Xtext_Integration">12.1.2. Xtext Integration</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:xtext_default_behaviour">12.1.2.1. Xtext default behaviour</a></li>
<li><a href="compilation.html#sec:n4js_requirements">12.1.2.2. N4JS requirements</a></li>
<li><a href="compilation.html#sec:compiler_discovery_in_ui">12.1.2.3. Compiler discovery in UI</a></li>
<li><a href="compilation.html#sec:compiler_discovery_in_headless">12.1.2.4. Compiler discovery in headless</a></li>
<li><a href="compilation.html#sec:general_generator_implementation">12.1.2.5. General generator implementation</a></li>
<li><a href="compilation.html#sec:general_generator_activation">12.1.2.6. General generator activation</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Overview_of_Input_Models">12.1.3. Overview of the Input Models</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Core_Generator">12.2. Generators</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:Compiler_Components">12.2.1. Generator Components</a></li>
<li><a href="compilation.html#sec:Generator_architecture">12.2.2. Generator architecture</a></li>
<li><a href="compilation.html#sec:Unified_Compiler_Configuration">12.2.3. Unified Compiler Configuration</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Transpilers">12.3. Transpilers</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:Phases">12.3.1. Overview</a></li>
<li><a href="compilation.html#relation-between-ast-and-im">12.3.2. Relation between AST and IM</a></li>
<li><a href="compilation.html#implementation-overview">12.3.3. Implementation Overview</a></li>
<li><a href="compilation.html#sec:Guidelines_for_Implementing_Transformations">12.3.4. Guidelines for Implementing Transformations</a></li>
<li><a href="compilation.html#symbol-table-in-the-im">12.3.5. Symbol Table in the IM</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:N4JS_to_EcmaScript_Transpiler">12.4. N4JS-to-EcmaScript Transpiler</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:Overview_of_Transformations">12.4.1. Overview of Transformations</a></li>
<li><a href="compilation.html#sec:Transpiling_members">12.4.2. Transpiling members</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:Transpiling_members__Delegating_members">12.4.2.1. Techniques for special member handling</a></li>
<li><a href="compilation.html#sec:Transpiling_members__Partial_shadowing_of_getter_setter_pairs">12.4.2.2. Partial shadowing</a></li>
<li><a href="compilation.html#sec:Transpiling_members__Consuming_or_inheriting_members_of_an_interface">12.4.2.3. Consuming or inheriting members of an interface</a></li>
<li><a href="compilation.html#sec:Transpiling_members__Static_polyfill">12.4.2.4. Static polyfill</a></li>
<li><a href="compilation.html#sec:Transpiling_members__API_implementation_stubs">12.4.2.5. API / implementation stubs</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Support_for_incomplete_API_implementation_testing_in_the_N4JS_to_EcmaScript_5_Transpiler">12.4.3. Support for incomplete API implementation testing</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:Modifications_in_Impl_projects">12.4.3.1. Modifications in Impl projects</a></li>
<li><a href="compilation.html#sec:Implementation_of_stub_generation">12.4.3.2. Implementation of stub-generation</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="compilation.html#sec:n4jsc_Headless_Compiler_Interface">12.5. n4jsc Headless Compiler Interface</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:building_the_headless_compiler">12.5.1. building the headless compiler</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="execution.html#_execution">13. Execution</a>
<ul class="sectlevel2">
<li><a href="execution.html#sec:N4JS_Project_Execution_And_Linking_Model">13.1. N4JS Project Execution And Linking Model</a>
<ul class="sectlevel3">
<li><a href="execution.html#subsec:N4JS_Execution_With_NodeJS">13.1.1. N4JS Execution With NodeJS</a></li>
</ul>
</li>
<li><a href="execution.html#sec:N4JS_Execution_And_Linking_File">13.2. N4JS Execution And Linking File</a>
<ul class="sectlevel3">
<li><a href="execution.html#subsec:NodeJS_Specific_ELF">13.2.1. NodeJS Specific ELF</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Runners-execution">13.3. Runners</a>
<ul class="sectlevel3">
<li><a href="execution.html#subsec:N4_Runtime_Environments_Convention">13.3.1. N4 Runtime Environments Convention</a></li>
<li><a href="execution.html#subsec:Passing_Information_from_IDE_to_Execution_Code_in_Runtime_Environment">13.3.2. Passing Information from IDE to Execution Code in Runtime Environment</a></li>
<li><a href="execution.html#subsec:Runners_Design">13.3.3. Runners Design</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Legacy_Execution_Engine">13.4. Legacy Execution Engine</a></li>
<li><a href="execution.html#sec:Design">13.5. Design</a>
<ul class="sectlevel3">
<li><a href="execution.html#sec:Usage_Outside_N4JSIDE">13.5.1. Usage Outside N4JSIDE</a>
<ul class="sectlevel4">
<li><a href="execution.html#sec:Use_Node_with_Maven">13.5.1.1. Use Node with Maven</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Usage_Inside_N4JSIDE">13.5.2. Usage Inside N4JSIDE</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Runtime_Injection">13.6. Runtime Injection</a>
<ul class="sectlevel3">
<li><a href="execution.html#sec:Running_String_Code">13.6.1. Running String Code</a></li>
<li><a href="execution.html#sec:Running_File_Code">13.6.2. Running File Code</a></li>
<li><a href="execution.html#sec:Injection_Code_Example">13.6.3. Injection Code Example</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#_tests">14. Tests</a>
<ul class="sectlevel2">
<li><a href="tests.html#sec:Performance_Tests">14.1. Performance Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Synthetic_Performance_Tests">14.1.1. Synthetic Performance Tests</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:Design_of_Generator">14.1.1.1. Design of Generator</a></li>
<li><a href="tests.html#sec:Design_of_Performance_Test_Execution">14.1.1.2. Design of Performance Test Configuration and Execution</a></li>
<li><a href="tests.html#sec:JUnit_Configuration">14.1.1.3. JUnit Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Test_Configuration">14.1.1.4. JUnitBenchmark Test Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Report_Configuration">14.1.1.5. JUnitBenchmark Report Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Run_Configuration">14.1.1.6. JUnitBenchmark Run Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Example">14.1.1.7. JUnitBenchmark Example</a></li>
<li><a href="tests.html#sec:Note_on_Jenkins_Job">14.1.1.8. Note on Jenkins Job</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#sec:ECMA_Tests">14.2. ECMA Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Grammar_Tests">14.2.1. Grammar Tests</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:Negative_Tests">14.2.1.1. Negative Tests</a></li>
<li><a href="tests.html#sec:Test_Exclusion">14.2.1.2. Test Exclusion</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#sec:Integration_Tests">14.3. Integration Tests</a></li>
<li><a href="tests.html#sec:Test_Helpers">14.4. Test Helpers</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Parameterized_N4JS_Tests">14.4.1. Parameterized N4JS tests</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:ParameterizedXtextRunner">14.4.1.1. ParameterizedXtextRunner</a></li>
<li><a href="tests.html#sec:TestCodeProvider">14.4.1.2. TestCodeProvider</a></li>
<li><a href="tests.html#sec:Example_Of_Parameterized_Parser_Test">14.4.1.3. Example of parameterized parser test</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#sec:Issue_Suppression">14.5. Issue Suppression</a></li>
<li><a href="tests.html#sec:Xpect_Tests">14.6. Xpect Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Xpect_Test_Setup">14.6.1. Xpect Test Setup</a></li>
<li><a href="tests.html#sec:Xpect_Issue_Suppression">14.6.2. Xpect Issue Suppression</a></li>
<li><a href="tests.html#sec:Xpect_Provided_Test_Methods">14.6.3. Xpect Provided Test Methods</a>
<ul class="sectlevel4">
<li><a href="tests.html#errors">14.6.3.1. errors</a></li>
<li><a href="tests.html#warnings">14.6.3.2. warnings</a></li>
</ul>
</li>
<li><a href="tests.html#sec:N4JS_Specific_Xpect_Test_Methods">14.6.4. N4JS Specific Xpect Test Methods</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:XPECT_noerrors">14.6.4.1. noerrors and nowarnings</a></li>
<li><a href="tests.html#sec:XPECT_scope">14.6.4.2. scope</a></li>
<li><a href="tests.html#sec:XPECT_scopeWithPosition">14.6.4.3. scopeWithPosition</a></li>
<li><a href="tests.html#sec:XPECT_scopeWithResource">14.6.4.4. scopeWithResource</a></li>
<li><a href="tests.html#sec:XPECT_binding">14.6.4.5. binding</a></li>
<li><a href="tests.html#sec:XPECT_linkedPathname">14.6.4.6. linkedPathname</a></li>
<li><a href="tests.html#sec:XPECT_type_of">14.6.4.7. type of</a></li>
<li><a href="tests.html#sec:XPECT_expectedType">14.6.4.8. expectedType</a></li>
<li><a href="tests.html#sec:XPECT_elementKeyword">14.6.4.9. elementKeyword</a></li>
<li><a href="tests.html#sec:XPECT_accessModifier">14.6.4.10. accessModifier</a></li>
<li><a href="tests.html#sec:XPECT_compileResult">14.6.4.11. compileResult</a></li>
<li><a href="tests.html#sec:XPECT_output">14.6.4.12. output</a></li>
<li><a href="tests.html#sec:XPECT_outputRegEx">14.6.4.13. outputRegEx</a></li>
<li><a href="tests.html#sec:XPECT_calculatedAccessModifier">14.6.4.14. calculatedAccessModifier</a></li>
<li><a href="tests.html#sec:XPECT_spec">14.6.4.15. spec</a></li>
<li><a href="tests.html#sec:XPECT_deadCode">14.6.4.16. deadCode</a></li>
<li><a href="tests.html#sec:XPECT_returnOrThrows">14.6.4.17. returnOrThrows</a></li>
<li><a href="tests.html#sec:XPECT_lint">14.6.4.18. lint</a></li>
<li><a href="tests.html#sec:XPECT_lintFails">14.6.4.19. lintFails</a></li>
</ul>
</li>
<li><a href="tests.html#sec:FIXME_Xpect_modifier">14.6.5. FIXME Xpect modifier</a></li>
<li><a href="tests.html#sec:Expectmatrix_Xpect_Test_Methods">14.6.6. Expectmatrix Xpect tests</a></li>
<li><a href="tests.html#xpect-lint-tests">14.6.7. Xpect Lint Tests</a></li>
</ul>
</li>
<li><a href="tests.html#xpect-proposal-tests">14.7. Xpect Proposal Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Validation_vs__Non_Validation">14.7.1. Validation vs. Non-Validation</a></li>
<li><a href="tests.html#sec:General_Proposal_Test_Features">14.7.2. General Proposal Test Features</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:Test_Variables">14.7.2.1. Test Variables</a></li>
<li><a href="tests.html#sec:Location_and_Selection">14.7.2.2. at – Location and Selection</a></li>
<li><a href="tests.html#sec:Multi_Line_Expectations_in_Proposal_Tests">14.7.2.3. Multi Line Expectations in Proposal Tests</a></li>
<li><a href="tests.html#sec:Timeout">14.7.2.4. Timeout and Performance</a></li>
</ul>
</li>
<li><a href="tests.html#proposals-verify-existence-of-proposals">14.7.3. proposals – Verify Existence of Proposals</a></li>
<li><a href="tests.html#sec:Verify_displayed_string">14.7.4. display – Verify displayed string</a></li>
<li><a href="tests.html#sec:Apply_Proposal">14.7.5. apply – Apply Proposal</a>
<ul class="sectlevel4">
<li><a href="tests.html#resource-application-in-other-files">14.7.5.1. resource – application in other files</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Content_Assist_Cycling">14.7.6. kind – Content Assist Cycling</a></li>
<li><a href="tests.html#fileValidVerify-validation-status">14.7.7. fileValid – Verify validation status</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Apply_Proposal_And_Execute_Tests">14.8. Apply Proposal And Execute Tests</a></li>
<li><a href="tests.html#sec:Organize_Imports_Test">14.9. Organize Imports Test</a>
<ul class="sectlevel3">
<li><a href="tests.html#organizeimports">14.9.1. organizeImports</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Access_Control_Test">14.10. Access Control Test</a>
<ul class="sectlevel3">
<li><a href="tests.html#test-scenarios">14.10.1. Test Scenarios</a></li>
<li><a href="tests.html#n4js-code-generator">14.10.2. N4JS Code Generator</a></li>
<li><a href="tests.html#xtext-issue-matcher">14.10.3. Xtext Issue Matcher</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Smoke_Tests">14.11. Smoke Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#how-to-handle-smoke-test-errors">14.11.1. How to handle smoke test errors?</a></li>
<li><a href="tests.html#smoketester-and-exceptionanalyzer">14.11.2. SmokeTester and ExceptionAnalyzer</a></li>
</ul>
</li>
<li><a href="tests.html#sec:UI_Tests_with_SWTBot">14.12. UI Tests with SWTBot</a>
<ul class="sectlevel3">
<li><a href="tests.html#writing-swtbot-tests">14.12.1. Writing SWTBot Tests</a></li>
<li><a href="tests.html#running-swtbot-tests">14.12.2. Running SWTBot Tests</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Debugging_UI_Tests">14.13. Debugging UI Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Connecting_to_the_X_server_on_the_build_node">14.13.1. Connecting to the X-server on the build-node</a></li>
<li><a href="tests.html#sec:Tools_to_investigate_the_java_stack">14.13.2. Tools to investigate the java-stack</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="ui_concepts.html#_ui-concepts">15. UI Concepts</a>
<ul class="sectlevel2">
<li><a href="ui_concepts.html#sec:User_Interface_Concepts">15.1. User Interface Concepts</a>
<ul class="sectlevel3">
<li><a href="ui_concepts.html#sec:Eclipse_UI_Concepts">15.1.1. Eclipse UI Concepts</a>
<ul class="sectlevel4">
<li><a href="ui_concepts.html#sec:Label_Provider">15.1.1.1. Label Provider</a></li>
<li><a href="ui_concepts.html#sec:Markers">15.1.1.2. Markers</a></li>
<li><a href="ui_concepts.html#sec:Commands__Toolbar_and_Menus">15.1.1.3. Commands, Toolbar and Menus</a></li>
<li><a href="ui_concepts.html#sec:Content_Assist">15.1.1.4. Content Assist</a></li>
<li><a href="ui_concepts.html#sec:Quick_Fixes">15.1.1.5. Quick Fixes</a></li>
<li><a href="ui_concepts.html#sec:Quick_Assist">15.1.1.6. Quick Assist</a></li>
<li><a href="ui_concepts.html#sec:Clean_Up_Actions">15.1.1.7. Clean Up Actions</a></li>
<li><a href="ui_concepts.html#sec:Save_Actions">15.1.1.8. Save Actions</a></li>
<li><a href="ui_concepts.html#sec:Auto_Edit">15.1.1.9. Auto Edit</a></li>
<li><a href="ui_concepts.html#sec:Template_Proposals">15.1.1.10. Template Proposals</a></li>
<li><a href="ui_concepts.html#sec:Outline_View___Quick_Outline">15.1.1.11. Outline View / Quick Outline</a></li>
<li><a href="ui_concepts.html#sec:Navigator__Package_Explorer__Project_Explorer">15.1.1.12. Navigator, Package Explorer, Project Explorer</a></li>
<li><a href="ui_concepts.html#sec:Hyperlinking_and_Navigation">15.1.1.13. Hyperlinking and Navigation</a></li>
<li><a href="ui_concepts.html#sec:Syntax_and_Semantic_Coloring">15.1.1.14. Syntax and Semantic Coloring</a></li>
<li><a href="ui_concepts.html#sec:Code_Formatter">15.1.1.15. Code Formatter</a></li>
<li><a href="ui_concepts.html#sec:Wizards">15.1.1.16. Wizards</a></li>
<li><a href="ui_concepts.html#sec:Cheat_Sheets">15.1.1.17. Cheat Sheets</a></li>
<li><a href="ui_concepts.html#sec:Context_sensitive_Help">15.1.1.18. Context-sensitive Help</a></li>
<li><a href="ui_concepts.html#sec:Hovers">15.1.1.19. Hovers</a></li>
<li><a href="ui_concepts.html#sec:Folding">15.1.1.20. Folding</a></li>
<li><a href="ui_concepts.html#sec:Customizable_validation___severity">15.1.1.21. Customizable validation / severity</a></li>
<li><a href="ui_concepts.html#sec:Proposals">15.1.1.22. Proposals</a></li>
</ul>
</li>
<li><a href="ui_concepts.html#sec:Non_Eclipse_UI_Concepts">15.1.2. Non-Eclipse UI Concepts</a>
<ul class="sectlevel4">
<li><a href="ui_concepts.html#sec:Overlays">15.1.2.1. Overlays</a></li>
<li><a href="ui_concepts.html#sec:Goto__Inferred__Type">15.1.2.2. Goto (Inferred) Type</a></li>
<li><a href="ui_concepts.html#sec:Postfix_Completion">15.1.2.3. Postfix Completion</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="ui_concepts.html#_user-interface-resources">15.2. User Interface Resources</a>
<ul class="sectlevel3">
<li><a href="ui_concepts.html#_icons">15.2.1. Icons</a>
<ul class="sectlevel4">
<li><a href="ui_concepts.html#_eclipse-platform-icons">15.2.1.1. Eclipse Platform Icons</a></li>
<li><a href="ui_concepts.html#_n4js-specific-icons">15.2.1.2. N4JS Specific Icons</a></li>
<li><a href="ui_concepts.html#_high-resolution-icons">15.2.1.3. High Resolution Icons</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="formatting.html#_formatting">16. Formatting</a>
<ul class="sectlevel2">
<li><a href="formatting.html#sec:FmtObjective">16.1. Objective</a>
<ul class="sectlevel3">
<li><a href="formatting.html#sec:FmtFormatting_Comments">16.1.1. Formatting Comments</a></li>
</ul>
</li>
<li><a href="formatting.html#sec:FmtArchitecture">16.2. Architecture</a>
<ul class="sectlevel3">
<li><a href="formatting.html#sec:Implementation_example">16.2.1. Implementation example</a></li>
</ul>
</li>
<li><a href="formatting.html#sec:FmtFormatter_Implementation_Guidelines">16.3. Formatter Implementation Guidelines</a></li>
<li><a href="formatting.html#sec:FmtConfiguration">16.4. Configuration</a></li>
<li><a href="formatting.html#sec:FmtUI_Integration">16.5. UI Integration</a></li>
<li><a href="formatting.html#sec:FmtUnit_Testing_with_Xpect">16.6. Unit Testing with Xpect</a></li>
</ul>
</li>
<li><a href="external_libraries.html#_external-libraries">17. External Libraries</a>
<ul class="sectlevel2">
<li><a href="external_libraries.html#sec:Major_Components">17.1. Major Components</a>
<ul class="sectlevel3">
<li><a href="external_libraries.html#subsec:External_Resources">17.1.1. External Resources</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Workspace">17.1.2. External Library Workspace</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Preference_Store">17.1.3. External Library Preference Store</a></li>
<li><a href="external_libraries.html#subsec:npm_Manager">17.1.4. Library Manager</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Builder_Helper">17.1.5. External Library Builder</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Xtext_Index_Persister">17.1.6. External Library Xtext Index Persister</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Preference_Page">17.1.7. External Library Preference Page</a></li>
</ul>
</li>
<li><a href="external_libraries.html#sec:Headless_External_Library_Support">17.2. Headless External Library Support</a>
<ul class="sectlevel3">
<li><a href="external_libraries.html#_custom-npm-settings">17.2.1. Custom npm settings</a></li>
</ul>
</li>
<li><a href="external_libraries.html#sec:lmFutureWork">17.3. Future Work</a>
<ul class="sectlevel3">
<li><a href="external_libraries.html#subsec:lmMultipleDependencyScope">17.3.1. Multiple Dependency Scope</a></li>
<li><a href="external_libraries.html#subsec:lmRunTestsFromLibrary">17.3.2. Run Tests from TestLibrary</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="json_support.html#sec:JSON_Support">18. JSON Support</a>
<ul class="sectlevel2">
<li><a href="json_support.html#sec:JSON_Parser">18.1. JSON Parser</a>
<ul class="sectlevel3">
<li><a href="json_support.html#sec:JSON_Parser_Unicode_Escaping">18.1.1. Escaping Unicode Control Characters in String Literals</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Empty_Text">18.1.2. Empty Text</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Nested_Structures">18.1.3. Nested Structures</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Whitespace">18.1.4. Whitespace</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Comments">18.1.5. Comments</a></li>
</ul>
</li>
<li><a href="json_support.html#sec:JSON_Language_Extensions">18.2. JSON Language Extensions</a>
<ul class="sectlevel3">
<li><a href="json_support.html#sec:JSON_Validator_Extensions">18.2.1. JSON Validator Extensions</a>
<ul class="sectlevel4">
<li><a href="json_support.html#sec:File_Specitic_Validator_Extensions">18.2.1.1. File-Specific Validator Extensions</a></li>
<li><a href="json_support.html#sec:JSON_Declarative_JSON_Validator_Extensions">18.2.1.2. Declarative JSON Validator Extensions</a></li>
</ul>
</li>
<li><a href="json_support.html#_json-resource-description-strategy">18.2.2. JSON Resource Description Strategy</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="jsdoc.html#_jsdoc">19. JSDoc</a>
<ul class="sectlevel2">
<li><a href="jsdoc.html#sec:Design_Rationale">19.1. Design Rationale</a>
<ul class="sectlevel3">
<li><a href="jsdoc.html#_general-design">19.1.1. General Design</a></li>
<li><a href="jsdoc.html#sec:Type_Expressions">19.1.2. Type Expressions</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="docexporter.html#_docexporter">20. DocExporter</a>
<ul class="sectlevel2">
<li><a href="docexporter.html#sec:Specification_Exporter">20.1. Specification Exporter</a></li>
</ul>
</li>
<li><a href="rename_refactoring.html#_rename-refactoring">21. Rename Refactoring</a>
<ul class="sectlevel2">
<li><a href="rename_refactoring.html#_rename-refactoring-ui-interaction">21.1. Rename Refactoring UI interaction</a></li>
<li><a href="rename_refactoring.html#_renameelementprocessor-interaction">21.2. RenameElementProcessor interaction</a></li>
</ul>
</li>
<li><a href="flow_graphs.html#chap:flowgraphs">22. Flow Graphs</a>
<ul class="sectlevel2">
<li><a href="flow_graphs.html#sec:flowgraphs_overview">22.1. Flow graphs overview</a>
<ul class="sectlevel3">
<li><a href="flow_graphs.html#_internal-graph">22.1.1. Internal graph</a></li>
<li><a href="flow_graphs.html#_optimizations">22.1.2. Optimizations</a></li>
<li><a href="flow_graphs.html#_api-for-client-analyses">22.1.3. API for client analyses</a>
<ul class="sectlevel4">
<li><a href="flow_graphs.html#_mapping-from-internal-to-ast-elements">22.1.3.1. Mapping from internal to AST elements</a></li>
<li><a href="flow_graphs.html#_graph-visitor">22.1.3.2. Graph visitor</a></li>
<li><a href="flow_graphs.html#_graph-explorer">22.1.3.3. Graph explorer</a></li>
<li><a href="flow_graphs.html#_branch-walker">22.1.3.4. Branch walker</a></li>
<li><a href="flow_graphs.html#_example-1-compute-string-for-each-path">22.1.3.5. Example 1: Compute string for each path</a></li>
<li><a href="flow_graphs.html#_path-quantor">22.1.3.6. Path quantor</a></li>
</ul>
</li>
<li><a href="flow_graphs.html#_control-flow-analyses">22.1.4. Control flow analyses</a>
<ul class="sectlevel4">
<li><a href="flow_graphs.html#_dead-code-analysis">22.1.4.1. Dead code analysis</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="flow_graphs.html#sec:dataflow">22.2. Dataflow</a>
<ul class="sectlevel3">
<li><a href="flow_graphs.html#_dataflow-graph">22.2.1. Dataflow graph</a></li>
<li><a href="flow_graphs.html#_dataflow-analyses">22.2.2. Dataflow analyses</a>
<ul class="sectlevel4">
<li><a href="flow_graphs.html#_def-def-def-nothing-analysis">22.2.2.1. Def&#8594;Def / Def&#8594;Nothing analysis</a></li>
<li><a href="flow_graphs.html#_def-use-decl-analysis">22.2.2.2. Def|Use&#8592;Decl analysis</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="publish_npms.html#sec:publish-npms-to-public">23. Publish npms</a>
<ul class="sectlevel2">
<li><a href="publish_npms.html#sec:publish-npms-n4js-maven">23.1. Publish n4js-libs to during  maven build</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Hints">Appendix A: Hints</a>
<ul class="sectlevel2">
<li><a href="appendix_a_hints.html#sec:XtextInjection">A.1. Xtext Injection</a>
<ul class="sectlevel3">
<li><a href="appendix_a_hints.html#sec:DI_MultipleInjectors_Singletons">A.1.1. Multiple Injectors and Singletons</a>
<ul class="sectlevel4">
<li><a href="appendix_a_hints.html#sec:DI_avoid_duplicate_singletons">A.1.1.1. Avoiding duplicate singletons</a>
<ul class="sectlevel5">
<li><a href="appendix_a_hints.html#sec:DI_binding_in_shared">A.1.1.1.1. Defining binding in the shared injector</a></li>
<li><a href="appendix_a_hints.html#sec:DI_binding_in_custom">A.1.1.1.2. Defining binding in the custom injector</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:DI_Hints">A.1.2. Dependency Injection Hints</a>
<ul class="sectlevel4">
<li><a href="appendix_a_hints.html#sec:DI_custom_bundle">A.1.2.1. Use DI in custom bundle, use DI with extensions</a>
<ul class="sectlevel5">
<li><a href="appendix_a_hints.html#sec:DI_custom_bundle_problem">A.1.2.1.1. Problem</a></li>
<li><a href="appendix_a_hints.html#sec:DI_custom_bundle_solution">A.1.2.1.2. Solution</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Access_Other_DSL_Injector">A.1.2.2. How do I get the Guice Injector of my language?</a>
<ul class="sectlevel5">
<li><a href="appendix_a_hints.html#sec:DSL_Injector_UI_context">A.1.2.2.1. UI context</a></li>
<li><a href="appendix_a_hints.html#sec:DSL_Injector_Non_UI_context">A.1.2.2.2. Non UI context but with injection context</a></li>
<li><a href="appendix_a_hints.html#sec:DSL_Injector_Non_UI_non_injection_context">A.1.2.2.3. Non UI context without injection context</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Cancel_Indicator">A.1.2.3. How do I get cancel indicators in different contexts?</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Eclipse">A.2. Eclipse</a>
<ul class="sectlevel3">
<li><a href="appendix_a_hints.html#sec:Show_Xtext_Index">A.2.1. Show the current Xtext index</a></li>
<li><a href="appendix_a_hints.html#sec:Plugin_spy">A.2.2. Plug-in spy</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Maven-hints">A.3. Maven</a>
<ul class="sectlevel3">
<li><a href="appendix_a_hints.html#how-to-check-for-maven-mojo-updates">A.3.1. How to check for Maven MOJO updates</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#_module-loading">Appendix B: Module Loading</a>
<ul class="sectlevel2">
<li><a href="appendix_b_module_loading.html#sec:Dependency_Management">B.1. Dependency Management</a></li>
<li><a href="appendix_b_module_loading.html#ecmascript-modules">B.2. ECMAScript Modules</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:ES5_Modules_Systems">B.2.1. ES5 Modules Systems</a></li>
<li><a href="appendix_b_module_loading.html#sec:ES6_Modules">B.2.2. ES6 Modules</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:ECMAScript_Module_Loaders">B.3. ECMAScript Module Loaders</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:ES6_Module_Loaders">B.3.1. ES6 Module Loaders</a></li>
<li><a href="appendix_b_module_loading.html#sec:Polyfills_for_ES6_Module_Loaders">B.3.2. Polyfills for ES6 Module Loaders</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:es6_module_loader">B.3.2.1. es6-module-loader</a></li>
<li><a href="appendix_b_module_loading.html#sec:SystemJS">B.3.2.2. SystemJS</a></li>
<li><a href="appendix_b_module_loading.html#sec:Demo">B.3.2.3. Demo</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#case-study-typescript">B.4. Case Study : TypeScript</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:ES6_Modules_Support">B.4.1. ES6 Modules Support</a></li>
<li><a href="appendix_b_module_loading.html#sec:TypeScript_and_Module_Loading">B.4.2. TypeScript and Module Loading</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Cyclic_Dependencies">B.5. Cyclic Dependencies</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:Setup">B.5.1. Setup</a></li>
<li><a href="appendix_b_module_loading.html#sec:Transpile_and_Execute">B.5.2. Transpile and Execute</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Module_Format___AMD">B.5.2.1. Module Format = AMD</a></li>
<li><a href="appendix_b_module_loading.html#sec:Module_Format___CommonJS">B.5.2.2. Module Format = CommonJS</a></li>
<li><a href="appendix_b_module_loading.html#sec:Module_Format___SystemJS">B.5.2.3. Module Format = SystemJS</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Conclusion">B.5.3. Conclusion</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#system.register-as-transpilation-target">B.6. System.register as transpilation target</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:Introduction">B.6.1. Introduction</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:External_Transpilers">B.6.1.1. External Transpilers</a></li>
<li><a href="appendix_b_module_loading.html#sec:Example_of_a_System_register_module">B.6.1.2. Example of a System.register module</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Structure_of_a_System_register_module">B.6.2. Structure of a System.register module</a></li>
<li><a href="appendix_b_module_loading.html#_transpilation-hints">B.6.3. Transpilation Hints</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Handling_Imports">B.6.3.1. Handling Imports</a></li>
<li><a href="appendix_b_module_loading.html#sec:__exportFn__">B.6.3.2. &lt;&lt;exportFn&gt;&gt;</a></li>
<li><a href="appendix_b_module_loading.html#sec:Handling_Exports">B.6.3.3. Handling Exports</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Examples_w__Circular_Dependencies">B.6.4. Examples w/ Circular Dependencies</a></li>
<li><a href="appendix_b_module_loading.html#sec:N4JS_Examples_w__Circular_Dependencies">B.6.5. N4JS Examples w/ Circular Dependencies</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Unresolved_Cyclic_Dependencies">B.6.5.1. Unresolved Cyclic Dependencies</a></li>
<li><a href="appendix_b_module_loading.html#sec:Variables___Functions">B.6.5.2. Examples with Variables &amp; Functions</a></li>
<li><a href="appendix_b_module_loading.html#sec:Classes">B.6.5.3. Examples with Classes</a></li>
<li><a href="appendix_b_module_loading.html#sec:Examples_with_SubClassing">B.6.5.4. Examples with SubClassing</a></li>
<li><a href="appendix_b_module_loading.html#sec:Miscellaneous">B.6.5.5. Miscellaneous</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#_resources">B.6.6. Resources</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:CommonJS_as_transpilation_target">B.7. CommonJS as transpilation target</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#_introduction-2">B.7.1. Introduction</a></li>
<li><a href="appendix_b_module_loading.html#sec:Transpilation_Hints">B.7.2. Transpilation Hints</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Import_Statements">B.7.2.1. Import Statements</a></li>
<li><a href="appendix_b_module_loading.html#sec:Export_Statements">B.7.2.2. Export Statements</a></li>
<li><a href="appendix_b_module_loading.html#sec:Tracking_Live_Bindings">B.7.2.3. Tracking Live Bindings</a></li>
<li><a href="appendix_b_module_loading.html#sec:A_complete_example">B.7.2.4. A complete example</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#_resources-2">B.7.3. Resources</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_c_license.html#sec:License">Appendix C: License</a></li>
<li><a href="appendix_d_acronyms.html#sec:Acronyms">Appendix D: Acronyms</a></li>
<li><a href="appendix_e_bibliography_and_footnotes.html#_bibliography-and-footnotes">Appendix E: Bibliography and Footnotes</a></li>
</ul>
</div>
</div>
<div id="content"><div class="sect1">
<h2 id="_type-system"><a class="anchor" href="#_type-system"></a><a class="link" href="#_type-system">6. Type System</a></h2>
<div class="sectionbody">
<div class="sect2 language-n4js">
<h3 id="sec:Type_Model_and_Grammar"><a class="anchor" href="#sec:Type_Model_and_Grammar"></a><a class="link" href="#sec:Type_Model_and_Grammar">6.1. Type Model and Grammar</a></h3>
<div class="paragraph">
<p>The type model is used to define actual types and their relations (meta-model is defined by means of Xcore in file <code>Types.xcore</code>)
and also references to types (meta-model in <code>TypeRefs.xcore</code>). The type model is built via the <code>N4JSTypesBuilder</code> when a resource
is loaded and processed, and most type related tasks work only on the type model. Some types that are (internally) available
in N4JS are not defined in N4JS, but instead in a special, internal type language not available to N4JS developers, called N4TS
and defined in file <code>Types.xtext</code>.</p>
</div>
<div class="paragraph">
<p>The types are referenced by AST elements; vice versa the AST elements can be referenced from the types (see <code>SyntaxRelatedTElement</code>).
This backward reference is a simple reference to an EObject.</p>
</div>
<div class="sect3">
<h4 id="sec:Type_Model_Overview"><a class="anchor" href="#sec:Type_Model_Overview"></a><a class="link" href="#sec:Type_Model_Overview">6.1.1. Type Model Overview</a></h4>
<div class="paragraph">
<p>The following figure, <a href="#fig:cd_typeAndTypeRefHierarchy">Types and Type References</a>, shows the classes of the type model and their inheritance relations, both the actual type definitions as defined in <code>Types.xcore</code> and the type references defined in <code>TypeRefs.xcore</code>. The most important type reference is the <code>ParameterizedTypeRef</code>; it is used for most user-defined references, for both parameterized and non-parameterized references. In the latter case, the list of type arguments is empty.</p>
</div>
<div id="fig:cd_typeAndTypeRefHierarchy" class="imageblock">
<div class="content">
<img src="chapters/06_typesystem/images/cd_typeModelHierarchy_allInOne.png" alt="cd typeModelHierarchy allInOne">
</div>
<div class="title">Figure 8. Type Model Overview: Types in the upper half and Type References in the lower half.</div>
</div>
<div class="paragraph">
<p>Most types are self-explanatory. <code>TypeDefs</code> is the container element used in N4TS. Note that not all types and properties of types are available in N4JS – some can only be used in the N4TS language or be inferred by the type system for internal purposes. Some types need some explanation:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>TObjectPrototype</code>: Metatype for defining built-in object types such as <code>Object</code> or <code>Date</code>, only available in N4TS.</p>
</li>
<li>
<p><code>VirtualBaseType</code>: This type is not available in N4JS. It is used to define common properties provided by all types of a certain metatype. E.g., it is used for defining some properties shared by all enumerations (this was the reason for introducing this type).</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>We distinguish four kinds of types as summarized in <a href="#tab:KindOfTypes">Kind Of Types</a>. Role is an internal construct for different kind of users who can define the special kind of type. The language column refers to the language used to specify the type; which is either N4JS or N4TS.</p>
</div>
<table id="tab:KindOfTypes" class="tableblock frame-all grid-all spread">
<caption class="title">Table 1. Kind of Types</caption>
<colgroup>
<col style="width: 10%;">
<col style="width: 10%;">
<col style="width: 10%;">
<col style="width: 70%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Kind</th>
<th class="tableblock halign-left valign-top">Language</th>
<th class="tableblock halign-left valign-top">Role</th>
<th class="tableblock halign-left valign-top">Remark</th>
</tr>
</thead>
<tbody>
<tr>
<th class="tableblock halign-left valign-top"><p class="tableblock">user</p></th>
<th class="tableblock halign-left valign-top"><p class="tableblock">N4JS</p></th>
<th class="tableblock halign-left valign-top"><p class="tableblock">developer</p></th>
<td class="tableblock halign-left valign-top"><p class="tableblock">User defined types, such as declared classes or functions. These types are to be explicitly defined or imported in the code.</p></td>
</tr>
<tr>
<th class="tableblock halign-left valign-top"><p class="tableblock">library</p></th>
<th class="tableblock halign-left valign-top"><p class="tableblock">N4JSD</p></th>
<th class="tableblock halign-left valign-top"><p class="tableblock">developer</p></th>
<td class="tableblock halign-left valign-top"><p class="tableblock">Type declarations only, comparable to C header files, without implementation. Used for defining the API of 3rd party libraries. These type definitions are to be explicitly defined or imported in the code.</p></td>
</tr>
<tr>
<th class="tableblock halign-left valign-top"><p class="tableblock">builtin</p></th>
<th class="tableblock halign-left valign-top"><p class="tableblock">N4TS</p></th>
<th class="tableblock halign-left valign-top"><p class="tableblock">smith</p></th>
<td class="tableblock halign-left valign-top"><p class="tableblock">Built-in ECMAScript objects interpreted as types. E.g., <code>String</code>, <code>Date</code>, <code>Math</code>. These types are provided by N4JS and are always available.</p></td>
</tr>
<tr>
<th class="tableblock halign-left valign-top"><p class="tableblock">primitive</p></th>
<th class="tableblock halign-left valign-top"><p class="tableblock">N4TS</p></th>
<th class="tableblock halign-left valign-top"><p class="tableblock">smith</p></th>
<td class="tableblock halign-left valign-top"><p class="tableblock">Primitive ECMAScript (and N4JS ties), such as <code>string</code>, <code>number</code>, <code>pathselector&lt;T&gt;</code>, <code>i18n</code>, and also <code>any</code>, <code>undefined</code> and <code>void</code>. These types are provided by N4JS and are always available. Primitive types are described in detail in the spec (see chapter "Primitive ECMAScript Types").</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect3">
<h4 id="sec:Built_in_Types"><a class="anchor" href="#sec:Built_in_Types"></a><a class="link" href="#sec:Built_in_Types">6.1.2. Built-in and Primitive Types</a></h4>
<div class="paragraph">
<p>The built-in and primitive types are not defined by the user, i.e. N4JS programmer. Instead, they are defined in special
internal files using the internal N4TS language: <code>builtin_js.n4ts</code>, <code>builtin_n4.n4ts</code>, <code>primitives_js.n4ts</code>, <code>primitives_n4.n4ts</code>.</p>
</div>
</div>
<div class="sect3 language-n4js">
<h4 id="sec:Type_Model_DSL"><a class="anchor" href="#sec:Type_Model_DSL"></a><a class="link" href="#sec:Type_Model_DSL">6.1.3. Type Model DSL</a></h4>
<div class="paragraph">
<p>For defining built-in types and for tests, a special DSL called N4TS is provided by means of an Xtext grammar and generated
tools. The syntax is similar to n4js, but of course without method or function bodies, i.e. without any statements of expressions.
The grammar file is found in <code>Types.xtext</code>.</p>
</div>
<div class="paragraph">
<p>The following list documents some differences to N4JS:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>access modifiers directly support <code>Internal</code>, so no annotations are needed (nor supported) here.</p>
</li>
<li>
<p>besides N4 classifiers such as classes, the following classifiers can be defined:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p><code>object</code> define classes derived from object (predefined object types) Special features:</p>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
indexed
</td>
<td class="hdlist2">
<p>defined what type is returned in case of index access</p>
</td>
</tr>
</table>
</div>
</li>
<li>
<p><code>virtualBase</code> virtual base types for argument</p>
</li>
</ol>
</div>
</li>
<li>
<p><code>primitive</code> primitive types (number, string etc.) Special features:</p>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
indexed
</td>
<td class="hdlist2">
<p>defined what type is returned in case of index access</p>
</td>
</tr>
<tr>
<td class="hdlist1">
autoboxedType
</td>
<td class="hdlist2">
<p>defines to which type the primitive can be auto boxed</p>
</td>
</tr>
<tr>
<td class="hdlist1">
assignmnentCompatible
</td>
<td class="hdlist2">
<p>defines to which type the primitive is assignment compatible</p>
</td>
</tr>
</table>
</div>
</li>
<li>
<p>types <code>any</code>, <code>null</code>, <code>void</code>, <code>undefined</code> – special types.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Annotations are not supported in the types DSL.</p>
</div>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="sec:Type_System_Implementation"><a class="anchor" href="#sec:Type_System_Implementation"></a><a class="link" href="#sec:Type_System_Implementation">6.2. Type System Implementation</a></h3>
<div class="paragraph">
<p>The bulk of the type system&#8217;s functionality is implemented in packages <code>org.eclipse.n4js.typesystem[.constraints|.utils]</code>.
Client code, e.g. in validations, should only access the type system through the facade class <code>N4JSTypeSystem</code>.
Each of the main type system functions, called "judgments", are implemented in one of the concrete subclasses of
base class <code>AbstractJudgment</code>. Internally, the type system is using a constraint solver for various purposes;
entry point for this functionality is class <code>InferenceContext</code>. All these classes are a good entry point into
the code base, for investigating further details.</p>
</div>
<div class="paragraph">
<p>Some type information is cached (e.g., the type of an expression in the AST) and the above facade will take care
to read from the cache instead of re-computing the information every time, as far as possible. This type cache is
being filled in a dedicated phase during loading and processing of an N4JS resource;
see <a href="#sec:Type_Inference_combined_with_AST_Traversal">Type Inference of AST</a> and <a href="type_index.html#sec:N4JS_Resource_Load_States">N4JS Resource Load States</a> for details.</p>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="sec:Type_Inference_combined_with_AST_Traversal"><a class="anchor" href="#sec:Type_Inference_combined_with_AST_Traversal"></a><a class="link" href="#sec:Type_Inference_combined_with_AST_Traversal">6.3. Type Inference of AST</a></h3>
<div class="paragraph">
<p>Most judgments provided by the facade <code>N4JSTypeSystem</code> and implemented by subclasses of <code>AbstractJudgment</code> are used
ad-hoc whenever client code requires the information they provide. This is applied, in particular, to judgments</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>subtype</code></p>
</li>
<li>
<p><code>substTypeVariables</code></p>
</li>
<li>
<p><code>upperBound</code> / <code>lowerBound</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For judgment <code>type</code> footnote:<code class="Currently only for [language-n4js">type</code>, not for <code class="language-n4js">expectedType</code>,
but this may be changed in a future, further refactoring.], however, the processing is very different: we make
sure that the entire AST, i.e. all typable nodes of the AST, will be typed up-front in a single step, which
takes place during the <em>post-processing step</em> of an N4JSResource (see <a href="type_index.html#sec:N4JS_Resource_Load_States">N4JS Resource Load States</a>), which
also has a couple other responsibilities. By triggering post-processing when client code invokes the type judgment
for the first time for some random AST node (at the latest; usually it is triggered earlier), we make sure that
this sequence is always followed.</p>
</div>
<div class="paragraph">
<p>The remainder of this section will explain this single-step typing of the entire AST in detail.</p>
</div>
<div class="sect3">
<h4 id="sec:Type_Inference_combined_with_AST_Traversal__Background"><a class="anchor" href="#sec:Type_Inference_combined_with_AST_Traversal__Background"></a><a class="link" href="#sec:Type_Inference_combined_with_AST_Traversal__Background">6.3.1. Background</a></h4>
<div class="paragraph">
<p>Originally, the N4JS type system could be called with any <code>EObject</code> at any given time, without any knowledge of the
context. While this looked flexible in the beginning, it caused severe problems solving some inference cases, e.g.,
the rule environment had to be prepared from the outside and recursion problems could occur, and it was also
inefficient because some things had to be recalculated over and over again (although caching helped).</p>
</div>
<div class="paragraph">
<p>It is better to do type inferencing (that is, computing the type of expressions in general) in a controlled manner.
That is, instead of randomly computing the type of an expression in the AST, it is better to traverse the AST in a
well-defined traversal order. That way, it is guaranteed that certain other nodes have been visited and, if not,
either some special handling can kick in or an error can be reported. This could even work with XSemantics and the
declarative style of the rules. The difference is that by traversing the AST in a controlled manner, the rules can
make certain assumptions about the content of the rule-environment, such as that it always contains information
about type variable bindings and that it always contains information about expected types etc.</p>
</div>
<div class="paragraph">
<p>In that scenario, all AST nodes are visited and all types (and expected types) are calculated up-front. Validation
and other parts then do not need to actually compute types (by calling the actual, Xsemantics-generated type system);
instead, at that time all types have already been calculated and can simply be retrieved from the cache (this is
taken care of by the type system facade <code>N4JSTypeSystem</code>).</p>
</div>
<div class="paragraph">
<p>This also affects scoping, since all cross-references have to be resolved in this type computation step. However,
even for scoping this has positive effects: E.g., the receiver type in property access expressions is always visited
<em>before</em> visiting the selector. Thus it is not necessary to re-calculate the receiver type in order to perform scoping
for the selector.</p>
</div>
<div class="paragraph">
<p>The above refactoring was done in summer 2015. After this refactoring, we are still using Xsemantics to compute the
types, i.e. the <code>type</code>     judgement in Xsemantics was largely kept as before. However, the type judgment is invoked
in a controlled traversal order for each typable AST node in largely one step (controlled by <code>ASTProcessor</code> and <code>TypeProcessor</code>).</p>
</div>
<div class="paragraph">
<p>The upshot of this one-step type inference is that once it is completed, the type for every typable AST node is known.
Instead of storing this information in a separate model, this information will be stored and persisted in the type model
directly, as well as in transient fields of the AST <sup class="footnote">[<a id="_footnoteref_1" class="footnote" href="appendix_e_bibliography_and_footnotes.html#_footnote_1" title="View footnote.">1</a>]</sup>. Currently, this applies only to types, not expected types;
the inference of expected types could / should be integrated into the one-step inference as part of a future, further
refactoring.</p>
</div>
<table id="tab:typeInferenceBeforeAfter" class="tableblock frame-all grid-all spread">
<caption class="title">Table 2. Comparison of inference of type of AST nodes before / after refactoring.</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Before</th>
<th class="tableblock halign-left valign-top">After</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">ad-hoc type inference (when client code needs the type information)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">up-front type inference (once for entire AST;
later only reading from cache)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">started anywhere</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">starts with root, i.e. the <code>Script</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Xsemantics rules traverse the AST at will, uncontrolled</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">well-defined, controlled traversal order</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">lazy, on-demand resolution of <code>ComputedTypeRef</code>s (they contain the resolution logic)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">pro-active resolution of
<code>DeferredTypeRef</code>s (they themselves are dumb)</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect3">
<h4 id="sec:Triggering_Type_Inference_of_AST"><a class="anchor" href="#sec:Triggering_Type_Inference_of_AST"></a><a class="link" href="#sec:Triggering_Type_Inference_of_AST">6.3.2. Triggering</a></h4>
<div class="paragraph">
<p>The up-front type inference of the entire AST is part of the post-processing of every N4JSResource and is thus
triggered when post-processing is triggered. This happens when</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>someone directly calls <code>#performPostProcessing()</code> on an N4JSResource</p>
</li>
<li>
<p>someone directly calls <code>#resolveAllLazyCrossReferences()</code> on an N4JSResource,</p>
</li>
<li>
<p>EMF automatically resolves the first proxy, i.e. someone calls an EMF-generated getter for a value that is a proxy,</p>
</li>
<li>
<p>someone asks for a type for the first time, i.e. calls <code>N4JSTypeSystem#type()</code>,</p>
</li>
<li>
<p>&#8230;&#8203;</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Usually this happens after the types builder was run with <code>preLinking==false</code> and before validation takes place.
For details, see classes <code>PostProcessingAwareResource</code> and <code>N4JSPostProcessor</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="sec:Traversal_Order_During_Type_Inference_of_AST"><a class="anchor" href="#sec:Traversal_Order_During_Type_Inference_of_AST"></a><a class="link" href="#sec:Traversal_Order_During_Type_Inference_of_AST">6.3.3. Traversal Order</a></h4>
<div class="paragraph">
<p>The traversal order during post-processing is a bit tricky, as some things need to be done in a top-down order (only
few cases, for now <sup class="footnote">[<a id="_footnoteref_2" class="footnote" href="appendix_e_bibliography_and_footnotes.html#_footnote_2" title="View footnote.">2</a>]</sup>), others in a bottom-up order (e.g. the main typing of AST nodes),
and there is a third case in which several AST nodes are processed together (constraint-based type inference).</p>
</div>
<div class="paragraph">
<p>Figure <a href="#fig:traversalOrder">Order in which AST nodes are being processed during post-processing.</a> provides an example of an AST and shows in which order the nodes are processed. Green
numbers represent top-down processing, red numbers represent bottom-up processing and blue numbers represent the
processing of the surrounding yellow nodes in a single step.</p>
</div>
<div id="fig:traversalOrder" class="imageblock">
<div class="content">
<img src="chapters/06_typesystem/images/traversalOrder.png" alt="traversalOrder">
</div>
<div class="title">Figure 9. Order in which AST nodes are being processed during post-processing.</div>
</div>
<div class="paragraph">
<p>In the code, this is controlled by class <code>ASTProcessor</code>. The two main processing methods are</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>#processNode_preChildren()</code>, which will be invoked for all AST nodes in a top-down order (so top-down processing should be put here),</p>
</li>
<li>
<p><code>#processNode_postChildren()</code>, which will be invoked for all AST nodes in a bottom-up order (so bottom-up processing should be put here).</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The common processing of groups of adjacent yellow nodes (represented in the figure by the two yellow/brown
triangles) is achieved by <code>PolyProcessor</code> telling the <code>TypeProcessor</code> to</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>ignore certain nodes (all yellow nodes) and</p>
</li>
<li>
<p>invoke method <code>PolyProcessor#inferType()</code> for the root yellow node in each group (only the root!).
.
For details, see the two methods <code>#isResponsibleFor()</code> and <code>#isEntryPoint()</code> in <code>PolyProcessor</code>.</p>
</li>
</ol>
</div>
</div>
<div class="sect3">
<h4 id="sec:Cross_References_During_Type_Inference_of_AST"><a class="anchor" href="#sec:Cross_References_During_Type_Inference_of_AST"></a><a class="link" href="#sec:Cross_References_During_Type_Inference_of_AST">6.3.4. Cross-References</a></h4>
<div class="paragraph">
<p>While typing the entire AST, cross-references need special care. Three cases of cross-references need to be distinguished:</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
backward reference
</td>
<td class="hdlist2">
<p>= cross-reference within the same file to an AST node that was already processed</p>
<div class="ulist">
<ul>
<li>
<p>always legal</p>
</li>
<li>
<p>processing: simply read the type from the cache that is currently being filled</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="hdlist1">
forward reference
</td>
<td class="hdlist2">
<p>= cross-reference within the same file to an AST node that was not yet processed</p>
<div class="ulist">
<ul>
<li>
<p>usually illegal<br>
exception: legal if reference points to an <em>identifiable subtree</em> (a subtree of an AST with an identifiable element at its root)</p>
</li>
<li>
<p>processing: forward process the identifiable subtree and report back the type of its root</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="hdlist1">
references to other files
</td>
<td class="hdlist2">
<div class="ulist">
<ul>
<li>
<p>always legal, because they can, by nature, only point to an identifiable subtree in the other file&#8217;s AST</p>
</li>
<li>
<p>processing: either &#8230;&#8203;</p>
<div class="ulist">
<ul>
<li>
<p>read type from TModule obtained from index (if available), or</p>
</li>
<li>
<p>load other file from source, trigger its post-processing (if not in progress or completed already), forward process the identifiable subtree (if not processed already) and report back the type of its root.</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Note that for references to an ancestor (upward references) or successor (downward references) within an AST, the
classification as a forward or backward reference depends on whether we are in top-down or bottom-up processing.
Figure <a href="#fig:upwardDownward">Upward Downward</a> illustrates this: the left and right side show the same AST but on the
left side we assume a top down processing whereas on the right we assume a bottom up processing. On both sides,
backward references are shown in green ink (because they are unproblematic and always legal) and forward references
are shown in red ink. Now, looking at the two arrows pointing from a node to its parent, we see that it is classified
as a backward reference on the left side (i.e. top down case) but as a forward reference on the right side (i.e. bottom
down case). Conversely, an arrow from a node to its child is classified as a forward reference on the left side and as
a backward reference on the right side. Arrows across subtrees, however, are classified in the same way on the left and
right side (see the horizontal arrows at the bottom).</p>
</div>
<div id="fig:upwardDownward" class="imageblock">
<div class="content">
<img src="chapters/06_typesystem/images/upwardDownward.png" alt="upwardDownward">
</div>
<div class="title">Figure 10. Backward and forward references in top-down and bottom-up processing.</div>
</div>
</div>
<div class="sect3">
<h4 id="sec:Function_Accessor_Bodies_During_Type_Inference_of_AST"><a class="anchor" href="#sec:Function_Accessor_Bodies_During_Type_Inference_of_AST"></a><a class="link" href="#sec:Function_Accessor_Bodies_During_Type_Inference_of_AST">6.3.5. Function/Accessor Bodies</a></h4>
<div class="paragraph">
<p>An important exception to the basic traversal order shown in Figure <a href="#fig:traversalOrder">Order in which AST nodes are being processed during post-processing.</a> is that the body of all
functions (including methods) and field accessors is postponed until the end of processing. This is used to avoid
unnecessary cycles during type inference due to a function&#8217;s body making use of the function itself or some other
declarations on the same level as the containing function. For example, the following code relies on this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">let x = f();
function f(): X {
	if(x) {
		// XPECT noerrors --&gt; "any is not a subtype of X." at "x"
		return x;
	}
	return new X();
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Similar situation using fields and methods:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">class C {
	d = new D();
	mc() {
		// XPECT noerrors --&gt; "any is not a subtype of D." at "this.d"
		let tmp: D = this.d;
	}
}
class D {
	md() {
		new C().mc();
	}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>For details of this special handling of function bodies, see method <code>ASTProcessor#isPostponedNode(EObject)</code> and field
<code>ASTMetaInfoCache#postponedSubTrees</code> and the code using it. For further investigation, change <code>isPostponedNode()</code> to always
return false and debug with the two examples above (which will then show the incorrect errors mentioned in the XPECT
comments) or run tests to find more cases that require this handling.</p>
</div>
</div>
<div class="sect3">
<h4 id="sec:Poly_Expressions_During_Type_Inference_of_AST"><a class="anchor" href="#sec:Poly_Expressions_During_Type_Inference_of_AST"></a><a class="link" href="#sec:Poly_Expressions_During_Type_Inference_of_AST">6.3.6. Poly Expressions</a></h4>
<div class="paragraph">
<p>Polymorphic expressions, or <em>poly expressions</em> for short, are expressions for which the actual type depends on the
expected type and/or the expected type depends on the actual type. They require constraint-based type inference
because the dependency between the actual and expected type can introduce dependency cycles between the types of
several AST nodes which are best broken up by using a constraint-based approach. This is particularly true when
several poly expressions are nested. Therefore, poly expressions are inferred neither in top-down nor in bottom-up
order, but all together by solving a single constraint system.</p>
</div>
<div class="paragraph">
<p>Only a few types of expressions can be polymorphic; they are called <em>poly candidates</em>: array literals, object literals,
call expressions, and function expressions. The following rules tell whether a poly candidate is actually poly:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>ArrayLiteral</code> — always poly (because their type cannot be declared explicitly).</p>
</li>
<li>
<p><code>ObjectLiteral</code> — if one or more properties do not have a declared type.</p>
</li>
<li>
<p><code>CallExpression</code> — if generic &amp; not parameterized.</p>
</li>
<li>
<p><code>FunctionExpression</code> — if return type or type of one or more formal parameters is undeclared.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This is a simplified overview of these rules, for details see method <code>#isPoly(Expression)</code> in <code>AbstractPolyProcessor</code>.</p>
</div>
<div class="paragraph">
<p>The main logic for inferring the type of poly expressions is found in method <code>#inferType()</code> in class <code>PolyProcessor</code>.
It is important to note that this method will only be called for root poly expressions (see above). In short, the basic
approach is to create a new, empty <code>InferenceContext</code>, i.e. constraint system, add inference variables and constraints for
the root poly expression and all its nested poly expressions, solve the constraint system and use the types in the solution
as the types of the root and nested poly expressions. For more details see method <code>#inferType()</code> in class <code>PolyProcessor</code>.</p>
</div>
<div class="paragraph">
<p>So, this means that nested poly expressions do not introduce a new constraint system but instead simply extend their parent
poly’s constraint system by adding additional inference variables and constraints. <strong>But not every nested expression that is
poly is a nested poly expression in that sense!</strong> Sometimes, a new constraint system has to be introduced. For example:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>child poly expressions that appear as argument to a call expression are nested poly expressions (i.e. inferred in same constraint system as the parent call expression),</p>
</li>
<li>
<p>child poly expressions that appear as target of a call expression are <strong>not</strong> nested poly expressions and a new constraint system has to be introduced for them.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For details see method <code>#isRootPoly()</code> in <code>AbstractPolyProcessor</code> and its clients.</p>
</div>
</div>
<div class="sect3">
<h4 id="sec:Constraint_Solver_used_During_Type_Inference_of_AST"><a class="anchor" href="#sec:Constraint_Solver_used_During_Type_Inference_of_AST"></a><a class="link" href="#sec:Constraint_Solver_used_During_Type_Inference_of_AST">6.3.7. Constraint Solver</a></h4>
<div class="paragraph">
<p>The simple constraint solver used by the N4JS type system, mainly for the inference of poly expressions, is implemented
by class <code>InferenceContext</code> and the other classes in package <code>org.eclipse.n4js.typesystem.constraints</code>.</p>
</div>
<div class="paragraph">
<p>The constraint solving algorithm used here is largely modeled after the one defined in <code>The Java Language Specification 8</code>,
Chapter 18, but was adjusted in a number of ways, esp. by removing functionality not required for N4JS (e.g. primitive types,
method overloading) and adding support for specific N4JS language features (e.g. union types, structural typing).</p>
</div>
<div class="paragraph">
<p>For details see the API documentation of class <code>InferenceContext</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="sec:Type_Guards_During_Type_Inference_of_AST"><a class="anchor" href="#sec:Type_Guards_During_Type_Inference_of_AST"></a><a class="link" href="#sec:Type_Guards_During_Type_Inference_of_AST">6.3.8. Type Guards</a></h4>
<div class="paragraph">
<p>During AST post-processing, the control and data flow analyses are performed.
This means, that first a flow graph is created and then traversed.
During the traversal, a type guard analysis is performed which saves information by evaluating <code>instanceof</code> expressions.
As a result, the analysis provides a reliable set of RHS expressions of <code>instanceof</code> expressions for each AST element of type <code>IdentifierRef</code>.</p>
</div>
<div class="paragraph">
<p>This set is evaluated in the <code>TypeJudgments.java</code> when typing <code>IdentifierRef</code> elements.
In case the set is not empty, the types of all elements is calculated.
The type of the <code>IdentifierRef</code> will then become the intersection of its original type and all types previously calculated.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="sec:Structural_Typing"><a class="anchor" href="#sec:Structural_Typing"></a><a class="link" href="#sec:Structural_Typing">6.4. Structural Typing</a></h3>
<div class="paragraph">
<p>Structural typing as an optional subtyping mode in N4JS is implemented in <code>StructuralTypingComputer</code>, activated depending on
the value of property <code>typingStrategy</code> in <code>ParameterizedTypeRef</code> and its subclasses.</p>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Version 0.9<br>
Last updated 2019-08-08 13:15:33 CEST
</div>
</div>
<!-- ************* docinfo-footer *************************************************************** -->
<div class="Grid social" style="color:#d5dfea">
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <h2>Quick Links</h2>
    <ul>
      <li><a href="../downloads.html">Download</a></li>
      <li><a href="../userguides/index.html">Documentation</a></li>
      <li><a href="https://github.com/eclipse/n4js/">Source</a></li>
      <li><a href="https://github.com/eclipse/n4js/issues">Issues</a></li>
    </ul>
  </div>
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <br/><br/>
    <ul>
      <li><a href="https://www.eclipse.org/forums/index.php/f/365/">Forum</a></li>
      <li><a href="http://n4js.blogspot.de/">Blog</a></li>
      <li><a href="https://dev.eclipse.org/mailman/listinfo/n4js-dev">Mailing List</a></li>
      <li><a href="https://projects.eclipse.org/projects/technology.n4js">Eclipse Project Page</a></li>
      <li><a href="https://twitter.com/n4jsdev">Tweets by n4jsdev</a></li>
    </ul>
  </div>
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <br/><br/>
    <ul>
      <li><a href="http://www.eclipse.org/">Eclipse Home</a></li>
      <li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
      <li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
      <li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
      <li><a href="http://www.eclipse.org/legal/">Legal</a></li>
    </ul>
  </div>
  <div style="clear: both; height: 0; overflow: hidden;"></div>
</div>

<!-- ************* UI Scripts ************* -->
<script type="text/javascript" src="scripts/back-to-top.js"></script>

<script type="text/javascript" src="scripts/treeview.js"></script>
<script type="text/javascript" src="scripts/toc.js"></script>

<!-- ************* Prism.js Syntax Highlighting ************* -->
<script src="scripts/prism.js"></script>

<script type="text/javascript">
	// Add the 'toclist' id for search function
	$(".toc2 > ul").attr('id', 'toclist');
	// Generate a Search input form
	$("#toclist > li:first-of-type").before('<input type="text" id="pagesearch" onkeyup="search()" placeholder="Search for section...">');
	$("#toclist > li:first-of-type").before('<i id="clear" class="fa fa-times-circle-o"></i>');
	$("#clear").click(function(){
	    $("#pagesearch").val('');
	    search();
	    $('.toc2 > ul').treeView('collapseAll');
	});
	// intialize Treeview.js
	$(".toc2 > ul").treeView();
	// Initialize Scrollspy
</script>
<!-- ************* docinfo-footer *************************************************************** -->
</body>
</html>